MachineKeySection Class [IIS 7 and higher]

Article
07/13/2012

Defines the configuration settings that control the key generation and algorithms that are used in encryption, decryption, and media access control (MAC) operations in Forms authentication, view-state validation, and session-state application isolation.

Syntax

class MachineKeySection : ConfigurationSection

Methods

The following table lists the methods exposed by the MachineKeySection class.

Name	Description
GetAllowDefinition	(Inherited from ConfigurationSection.)
GetAllowLocation	(Inherited from ConfigurationSection.)
RevertToParent	(Inherited from ConfigurationSection.)
SetAllowDefinition	(Inherited from ConfigurationSection.)
SetAllowLocation	(Inherited from ConfigurationSection.)

Properties

The following table lists the properties exposed by the MachineKeySection class.

Name	Description
Decryption	A read/write trimmed string value that specifies the type of hashing algorithm used to decrypt data. The possible values are listed later in the Remarks section. The default is "Auto".
DecryptionKey	A read/write trimmed string value that either specifies the process by which the key is generated or contains text that is used to encrypt and decrypt data. The default is "AutoGenerate,IsolateApps". Note: Use the "AutoGenerate" string to specify that ASP.NET generates a random key and stores it in the Local Security Authority. The "AutoGenerate" string is part of the default value. If you add the "IsolateApps" modifier to the DecryptionKey value, ASP.NET generates a unique encrypted key for each application by using its application ID. "IsolateApps" is also part of the default value. If you need to support configuration across a network of Web servers (a Web farm), set the DecryptionKey property manually to ensure consistent configuration.
Location	(Inherited from ConfigurationSection.) A key property.
Path	(Inherited from ConfigurationSection.) A key property.
SectionInformation	(Inherited from ConfigurationSection.)
Validation	A read/write sint32 value that specifies the type of encryption that is used for validating data. The possible values are listed later in the Remarks section.
ValidationKey	A read/write trimmed string value that either specifies the process by which the key is generated or contains text that is used to validate encrypted data. The default is "AutoGenerate,IsolateApps". Note: When the EnableViewStateMAC property of the PagesSection class is true, ASP.NET uses the ValidationKey property to create a message authentication code to ensure that view state has not been tampered with. The validation key is also used to generate out-of-process, application-specific session IDs to ensure that session-state variables are isolated between applications. Use the "AutoGenerate" string to specify that ASP.NET generates a random key and stores it in the Local Security Authority. "The AutoGenerate" string is part of the default value. If you add the "IsolateApps" modifier to the ValidationKey value, ASP.NET generates a unique encrypted key for each application by using its application ID. "IsolateApps" is also part of the default value. If you need to support configuration across a network of Web servers (a Web farm), set the ValidationKey property manually to ensure consistent configuration.

Subclasses

This class contains no subclasses.

Remarks

Note

In order for the MachineKeySection class to work across a network of Web servers (a Web farm), the MachineKeySection properties must be configured explicitly and identically with a valid key value. The "AutoGenerate" value does not work for Web farms because it relies on a cryptographically random key that is persisted by only the local computer. This key cannot be decrypted by any other computer.

The following table lists the possible values for the Decryption property. The default is "Auto".

Value	Description
Auto	ASP.NET determines the algorithm with which to decrypt data based on default configuration settings.
AES	ASP.NET uses the AES algorithm to decrypt data.
3DES	ASP.NET uses the Triple DES algorithm to decrypt data.

The following table lists the possible values for the Validation property. The default is 1 (SHA1).

Value	Keyword	Description
0	MD5	ASP.NET uses MD5 (Message-Digest algorithm 5) encryption.
1	SHA1	ASP.NET uses SHA1 (Secure Hash Algorithm 1) encryption.
2	3DES	ASP.NET uses Triple DES (Data Encryption Standard) encryption.
3	AES	ASP.NET uses AES (Advanced Encryption Standard) encryption.

Example

The following example displays the MachineKeySection settings for the default Web site.

' Connect to the WMI WebAdministration namespace.
Set oWebAdmin = _
    GetObject("winmgmts:root\WebAdministration")

' Get the machine key section.
Set oSite = oWebAdmin.Get("Site.Name='Default Web Site'")
oSite.GetSection "MachineKeySection", oMKeySection

' Display the path and location.
WScript.Echo "Machine Key Section Settings"
WScript.Echo "----------------------------"
WScript.Echo "Path: " & oMKeySection.Path
WScript.Echo "Location: " & oMKeySection.Location

' Display the machine key settings.
WScript.Echo "Decryption: " & oMKeySection.Decryption

WScript.Echo "Decryption Key: " & _
    oMKeySection.DecryptionKey    

WScript.Echo "Validation: " & _
    ValidationText(oMKeySection.Validation)

WScript.Echo "Validation Key: " & oMKeySection.ValidationKey

' Convert the Validation enumeration values to text.
Function ValidationText(enumValue)
    Select Case enumValue
        Case 0
            ValidationText = "MD5"
        Case 1
            ValidationText = "SHA1"
        Case 2
            ValidationText = "3DES"
        Case 3
            ValidationText = "AES"
        Case Else
            ValidationText = "Undefined enumeration value."
    End Select
End Function

Inheritance Hierarchy

ConfigurationSection

MachineKeySection

Requirements

Type	Description
Client	Requires IIS 7 on Windows Vista.
Server	Requires IIS 7 on Windows Server 2008.
Product	IIS 7
MOF file	WebAdministration.mof